## 7.3. Imagemaps

We have experimented with various sorts of indexing. Bearing in mind that words are going out of fashion in many circles, we may want to present an index as some sort of picture. In some circumstances, two dimensions may work much better than one; selecting places from a map, for instance, is a natural example. The objective here is to let the client user click on images or areas of images and to deduce from the position of the cursor at the time of the click what he or she wants to do next.

Recently, browsers have improved in capability and client-side mapping (built into the returned HTML script) is becoming more popular. It is also possible to embed an imagemap in the HTML (see http://home.netscape.com/assist/net_sites/html_extensions_3.html). However, here we do it at the server end. The httpd.conf in ... /site.imap is as follows:

>     User webuser
>     Group webgroup
>     ServerName www.butterthlies.com
>     DocumentRoot /usr/www/site.imap/htdocs

>     AddHandler imap-file map
>     ImapBase map
>     #ImapDefault default.html
>     #ImapDefault error
>     ImapDefault referer
>     ImapDefault map

>     ImapMenu Formatted

The seven lines of note are the last. `AddHandler` sets up imagemap handling using files with the extension .map.

### 7.3.1. ImapBase

>     ImapBase [map|referer|URL]
>     Default: http://servername
>     Server config, virtual host, directory, .htaccess

This directive sets the base URL for the imagemap, as follows:

`map`

  The URL of the imagemap itself.

`referer`

  The URL of the referring document. If this is unknown, http://servername/ is used.

URL

  The specified URL.

If this directive is absent, the map base defaults to http://servername/, which is the same as the `DocumentRoot` directory.

### 7.3.2. Imap Errors

When things go wrong with imagemaps -- which we shall engineer by setting circles in bench.map and clicking on the corners of the picture -- the action to take is set first by a line in the file bench.map :

>     default [error|nocontent|map|referer|URL]

The meanings of the arguments are given under the next item. If this line is not present, then the directive `ImapDefault` takes over.

### 7.3.3. ImapDefault

>     ImapDefault [error|nocontent|map|URL]
>     Default: nocontent
>     Server config, virtual host, directory, .htaccess

There is a choice of actions (if you spell them incorrectly, no error message appears and no action results):

`error`

  This makes Apache serve up a standard error message, which appears on the browser (depending which one it is) as something like "Internal Server Error."

`nocontent`

  Apache ignores the request.

`map`

  Apache returns the message `Document moved here`.

`URL`

  Apache returns the URL. If it is relative, then it will be relative to the imagemap base. On this site we serve up the file default.html to deal with errors. It contains the message:

>     You're clicking in the wrong place

### 7.3.4. HTML File

The document we serve up is ... /htdocs/sides.html:

>     <html>
>     <body>
>     <h1>Welcome to Butterthlies Inc</h1>
>     <h2>Which Side of the Bench?</h2>
>     <p>Tell us on which side of the bench you like to sit
>     </p>
>     <hr>
>     <p>
>     <p align=center>
>     <A HREF="bench.map">
>     <IMG ISMAP SRC="bench.jpg" ALT="A picture of a bench">
>     </A>
>     <p align=center>
>     Click on the side you prefer
>     </body>
>     </html>

This displays the now familiar picture of the bench and asks you to indicate which side you prefer by clicking on it. You must include the ISMAP attribute in the <IMG> tag to activate this behavior. Apache's imagemap handler then refers to the file .../site.imap/htdocs/bench.map to make sense of the mouse-click coordinates. It finds the following lines in that file:

>     rect left.html 0,0 118,144
>     rect right.html 118,0 237,144

which set up two areas in the left and right halves of the image and designate the files left.html and right.html to be returned if the mouse click occurs in the corresponding rectangle. Notice that the points are expressed as x,y <whitespace>. If you click in the left rectangle, the URL www.butterthlies.com/left.html is accessed, and you see the message:

>     You like to sit on the left

and conversely for clicks on the right side. In a real application, these files would be menus leading in different directions; here they are simple text files:

>     You like to sit on the left
>     You like to sit on the right

In a real system, you might now want to display the contents of another directory, rather than the contents of a file (which might be an HTML document that itself is a menu). To demonstrate this, we have a directory, ... /htdocs/things, which contains the rubbish files 1, 2, 3. If we replace `left.html` in bench.map with `things`, as follows:

>     rect things 0,0 118,144
>     rect right.html 118,0 237,144

we see:

>     Index of /things
>     . Parent Directory
>     . 1
>     . 2
>     . 3

The formatting of this menu is not affected by the setting for `IMapMenu.`

How do we know what the coordinates of the rectangles are (for instance, `0,0 118,144)`? If we access sides.html and put the cursor on the picture of the bench, Netscape helpfully prints its coordinates on the screen, following the URL and displayed in a little window at the bottom of the frame. For instance:

>     http://192.168.123.2/bench.map?98,125

It is quite easy to miss this if the Netscape window is too narrow or stretches off the bottom of the screen. We can then jot down on a bit of paper that the picture runs from 0,0 at the top left corner to 237,144 at the bottom right. Half of 237 is 118.5, so 118 will do as the dividing line.

We are not limited to rectangles enclosing the cursor. We can have the following objects:

polygons

  Invoked with `poly`, followed by 3 to 100 points. Apache returns the polygon that encloses the cursor.

circles

  Invoked with `circle`, followed by the center and a point on the circle (so if the center is x,y and you want it to have a radius R , the point could be x+R,y or x,y-R). Apache returns the circle that encloses the cursor.

points

  Invoked with `point`, followed by its coordinates. Apache returns the nearest point to the cursor.

We divided the image of the bench into two rectangles:

>     0,0 118,144
>     118,0 237,144

The center points of these two rectangles are:

>     59,72
>     177,72

so we can rewrite bench.map as:

>     point left.html 59,72
>     point right.html 177,72

and get the same effect.

The version of bench.map for polygons looks like this:

>     poly left.html 0,0 118,0 118,144 0,144
>     poly right.html 118,0 237,0 237,144 118,114

For circles, we use the points above as centers and add 118/2=59 to the x-coordinates for the radius. This should give us two circles in which the cursor is detected and the rest of the picture (right in the corners, for instance) in which it is not.

>     circle left.html 59,72 118,72
>     circle right.html 177,72 237,72

The useful thing about circles for this exercise is that if we click in the corners of the picture we generate an error condition, since the corners are outside the circles, and thereby exercise `ImapDefault`.

There is a third directive for the configuration file.

### 7.3.5. ImapMenu

>     ImapMenu [none|formatted|semiformatted|unformatted]
>     Server config, virtual host, directory, .htaccess

This directive applies if mapping fails or if the browser is incapable of displaying images. If the site is accessed using a text-based browser such as Lynx, a menu is displayed showing the possibilities in the .map file:

>     MENU FOR /BENCH.MAP
>     --------------------------------------
>            things
>            right.html

This is formatted according to the argument given to `ImapMenu`. The effect above is produced by `formatted`. The manual explains the options as follows:

`formatted`

  A `formatted` menu is the simplest menu. Comments in the imagemap file are ignored. A level-one header is printed, then a horizontal rule, then the links, each on a separate line. The menu has a consistent, plain look close to that of a directory listing.

`semiformatted`

  In the `semiformatted` menu, comments are printed where they occur in the imagemap file. Blank lines are turned into HTML breaks. No header or horizontal rule is printed, but otherwise the menu is the same as a `formatted` menu.

`unformatted`

  Comments are printed; blank lines are ignored. Nothing is printed that does not appear in the imagemap file. All breaks and headers must be included as comments in the imagemap file. This gives you the most flexibility over the appearance of your menus, but requires you to treat your map files as HTML instead of plain text.

The argument `none` redisplays the `` document sides.html.

Copyright © 2001 O'Reilly & Associates. All rights reserved.